home *** CD-ROM | disk | FTP | other *** search
/ Best of www.BestZips.com (Collector's Edition) / Best of WWW.BESTZIPS.COM Collector's Edition (JCSM Shareware) (JCS Marketing).ISO / help_sys / hlpgn131.zip / demo.mac < prev    next >
Text File  |  1996-09-05  |  14KB  |  345 lines
  1. .rem(=============================================================)
  2. .rem(DEMO.MAC)
  3. .rem( )
  4. .rem(Created by the HelpGen Help Generator, version 1.30)
  5. .rem(Copyright ⌐ 1994-1995 by Rimrock Software)
  6. .rem(All rights reserved.)
  7. .rem(=============================================================)
  8.  
  9. .start(main,Contents,DEMO.bmp,Demo Help Contents)
  10. .top(Help)
  11. .top(Table of Contents)
  12. .n
  13. The DEMO help file example makes use of many of the HelpGen 
  14. .p(macro,macros) and .p(rtfcmds,RTF commands) that are documented 
  15. with HelpGen..n.n
  16. .in
  17. .bj(planhlp,newcheck.bmp)   .j(planhlp,Planning Your Help File).n
  18. .bj(createmac,newcheck.bmp)   .j(createmac,Creating the Macro File).n
  19. .bj(usemacros,newcheck.bmp)   .j(usemacros,Using HelpGen Macros and RTF Commands).n
  20. .bj(createhpj,newcheck.bmp)   .j(createhpj,Creating the Project File).n
  21. .bj(creatertf,newcheck.bmp)   .j(creatertf,Generating the RTF File).n
  22. .bj(createhlp,newcheck.bmp)   .j(createhlp,Generating the Help File).n
  23. .bj(testhlp,newcheck.bmp)   .j(testhlp,Testing the Help File).n.n
  24. .bj(glossary,newcheck.bmp)   .j1(Glossary).n
  25. .un
  26. .n
  27. Click on a check box to look at a topic..n.n
  28. If you are unfamiliar with how Windows Help works, choose
  29.  .b(Help | How To Use Help) from the Help menu now.
  30. .end
  31.  
  32. .com(=============================================================)
  33. .com( Icon topic.  Used for info about how the file is prepared.  )
  34. .com(=============================================================)
  35. .ent(icon,Information,Demo )
  36. This icon topic .b(must) be present.  It is activated by clicking 
  37. on the icon in the Table of Contents.  You may place your own 
  38. text here..n
  39. \qc
  40. .box
  41. \brdrth
  42. HelpGen and this demo are \'a9 1994-1995 Rimrock Software.
  43.   All rights reserved.
  44. .bend
  45. \ql
  46. .end
  47.  
  48. .com(=============================================================)
  49. .com( Planning your help file topic.)
  50. .com(=============================================================)
  51. .ent(planhlp,Planning Your Help File, )
  52. Planning the layout and contents of the help file is probably 
  53. the most important part of creating on-line help.  A poorly 
  54. conceived and implemented help file is almost worthless to a user.  
  55. They may not be able to find anything they are looking for in the 
  56. help file, and if they do find the correct item, it may not help 
  57. with their problems..n.n
  58. This part of help file generation doesn't have much to do with the 
  59. actual mechanics of creating the help file, but it .b(is) important, 
  60. nevertheless.  Some basic steps in planning a help file are detailed 
  61. below..n
  62. .in
  63. #b(Outline the Help Subjects)  Plan to have a few major sections, 
  64. and many minor sections.  For instance, one way to organize is 
  65. to use the basic outline of your user manual.  Another way is shown 
  66. below:.n.n
  67. \tab\tab .b(Introduction).n
  68. \tab\tab .b(How To).n
  69. \tab\tab .b(Menu Items).n
  70. \tab\tab\tab File.n
  71. \tab\tab\tab\tab Open.n
  72. \tab\tab\tab\tab Close.n
  73. \tab\tab\tab\tab Exit.n
  74. \tab\tab\tab Edit.n
  75. \tab\tab\tab\tab Cut.n
  76. \tab\tab\tab\tab Copy.n
  77. \tab\tab\tab\tab Paste.n.n
  78. \tab This outline can go down as many levels as you want, but 
  79. anything more than about 4 levels is too complicated for a normal 
  80. user to navigate.  Once you have this basic outline, you essentially 
  81. have each of the topics that will be discussed in the help file.  
  82. Each level of the outline except the lowest level corresponds to a 
  83. single display page in the help file.  Each topic on the lowest 
  84. level of the outline corresponds to a single display page in the 
  85. help file..n.n
  86. \tab Continuing with our example above, then, the Table of Contents 
  87. page would contain the Introduction, How To and Menu Items topics.  
  88. If a user clicked on Menu Items, they would move to a page titled 
  89. Menu Items, which contains File and Edit topics.  Clicking on the 
  90. File item, they would move to a page containing the Open, Close and 
  91. Exit topics.  And finally, clicking on Open would move to a page 
  92. that explains the File | Open menu item..n
  93. #b(Create Topic Tags)  Each item on each level of the outline should 
  94. have a single word 'tag' that can be used to reference it to.  Go 
  95. through the outline and create a tag for each outline item.  We will 
  96. use these when we add the topics to the macro file..n.n
  97. \tab\tab .b(Introduction) - intro.n
  98. \tab\tab .b(How To) - howto.n
  99. \tab\tab .b(Menu Items) - menuitems.n
  100. \tab\tab\tab File - file.n
  101. \tab\tab\tab\tab Open - fileopen.n
  102. \tab\tab\tab\tab Close - fileclose.n
  103. \tab\tab\tab\tab Exit - fileexit.n
  104. \tab\tab\tab Edit - edit.n
  105. \tab\tab\tab\tab Cut - editcut.n
  106. \tab\tab\tab\tab Copy - editcopy.n
  107. \tab\tab\tab\tab Paste - editpaste.n
  108. #b(Flesh Out the Outline)  What you are really doing is writing a 
  109. user manual that will be read on-line in a non-linear (hypertext) 
  110. fashion.  Much of what you would normally say in a manual will be 
  111. included in the on-line help..n.n
  112. \tab Write explanations for each of the items on the lowest level of 
  113. your outline.  Use graphics (\'2eBMP files) and/or examples 
  114. liberally to explain the subject (a picture really .i(is) worth 1000 
  115. words)..n
  116. #b(Mark Definitions)  When you have completely written all the text 
  117. for your help file, go back and circle the terms that you think 
  118. the user will have trouble with, and that need to be defined.  These 
  119. terms will form the basis of your glossary.  The first time such a 
  120. term is encountered in .i(any) topic, it should be marked with a 
  121. \'2ep or \'2ep1 and should be explained in a \'2epent entry.  Create 
  122. a topic tag for each of the terms..n
  123. #b(Create the Macro File)  You are now ready to create and edit a 
  124. macro file for your on-line help..n
  125. .un
  126. .end
  127.  
  128. .com(=============================================================)
  129. .com( Creating the macro file topic. )
  130. .com(=============================================================)
  131. .ent(createmac,Creating the Macro File, )
  132. Now that you have your help topics outlined and fleshed out, you can 
  133. create and edit a macro file for your help..n
  134. .in
  135. #n(1)Continuing with the example we started in .b(Planning Your Help File,) 
  136. let's create an initial macro file.  Click on 
  137. .b(File | Open Macro File) and type in 'MYHELP' for a file name.  
  138. HelpGen will ask if you wish to create this file.  Click on the 
  139. 'Yes' button and MYHELP will be created..n
  140. #n(2)Now let's do some editing on this file.  Click on 
  141. .b(Edit | Macro File.)  The text editor should appear, with the 
  142. newly created MYHELP.MAC displayed in it.  Let's use the DEMO.BMP 
  143. file for the icon, change the table of contents header from xxxx to 
  144. Table of Contents and add the first level of our outline to the 
  145. table of contents topic:.n.n
  146. .[
  147. \'2erem(=============================================================).n
  148. \'2erem(MYHELP.MAC).n
  149. \'2erem( ).n
  150. \'2erem(Created by the HelpGen Help Generator, version 1.20).n
  151. \'2erem(Copyright \'a9 1994 by Rimrock Software).n
  152. \'2erem(All rights reserved.).n
  153. \'2erem(=============================================================).n
  154. .n
  155. \'2estart(main,Contents,DEMO\'2eBMP,Table of Contents).n
  156. \'2etop(Help).n
  157. \'2etop(Table of Contents).n
  158. .n
  159. \'2es.n
  160. \'2ein.n
  161. \'23\'23\'2ej(intro,Introduction).n
  162. \'23\'23\'2ej(howto,How To).n
  163. \'23\'23\'2ej(menuitems,Menu Items).n
  164. \'2eun.n
  165. \'2eend.n
  166. .n
  167. \'2eent(icon,Information,Icon ).n
  168. This icon topic \'2eb(MUST) be present.  It is activated by clicking 
  169. on the icon in the Table of Contents.  You may place your own 
  170. text here..n
  171. \'2eend.n
  172. .n
  173. \'2eend_file.n.n
  174. .]
  175. Note that we dress up the topics by indenting them (\'2ein and 
  176. \'2eun) and by putting a bullet in front of them (\'23\'23).  We 
  177. can also dress up a topic with colored text, but .c(1,DON'T) .c(2,GET) 
  178. .c(3,CARRIED) .c(4,AWAY) .c(10,WITH) .c(11,COLORS), .c(12,IT) .c(13,LOOKS) 
  179. .c(14,BAD).  We shouldn't compile this example until we add the entries 
  180. for the three jumps we just added:.n.n
  181. .[
  182. \'2estart(main,Contents,DEMO\'2eBMP,Table of Contents).n
  183. \'2etop(Help).n
  184. \'2etop(Table of Contents).n
  185. .n
  186. \'2es.n
  187. \'2ein.n
  188. \'23\'23\'2ej(intro,Introduction).n
  189. \'23\'23\'2ej(howto,How To).n
  190. \'23\'23\'2ej(menuitems,Menu Items).n
  191. \'2eun.n
  192. \'2eend.n
  193. .n
  194. \'2eent(icon,Information,Icon ).n
  195. This icon topic \'2eb(MUST) be present.  It is activated by clicking 
  196. on the icon in the Table of Contents.  You may place your own 
  197. text here..n
  198. \'2eend.n.n
  199. \'2eent(intro,Introduction, ).n
  200. \'2eend.n.n
  201. \'2eent(howto,How To, ).n
  202. \'2eend.n.n
  203. \'2eent(menuitems,Menu Items, ).n
  204. \'2eend.n
  205. .n
  206. \'2eend_file.n.n
  207. .]
  208. Now we can compile it if we want to, but let's continue.  Next, we 
  209. add the second level of the outline.  In this case, it means adding 
  210. to the Menu Items topic, and adding new topics for the third 
  211. outline level:.n.n
  212. .[
  213. \'2eent(menuitems,Menu Items, ).n
  214. \'2ein.n
  215. \'23\'23\'2ej(file,File).n
  216. \'23\'23\'2ej(edit,Edit).n
  217. \'2eun.n
  218. \'2eend.n.n
  219. \'2eent(file,File Menu,The ).n
  220. \'2eend.n.n
  221. \'2eent(edit,Edit Menu,The ).n
  222. \'2eend.n
  223. .n
  224. \'2eend_file.n.n
  225. .]
  226. We continue to add new jumps and new topics until we reach the last 
  227. level of the outline, where all the text will be entered.
  228. .end
  229.  
  230. .com(=============================================================)
  231. .com( Using HelpGen macros and RTF commands topic. )
  232. .com(=============================================================)
  233. .ent(usemacros,Using HelpGen Macros and RTF Commands, )
  234. If you have looked at .b(Creating the Macro File,) you will see that 
  235. we have already used many of the basic HelpGen macros.  The 
  236. remaining macros and RTF commands are used to primarily dress up 
  237. the help file, to make it more interesting and easier to use 
  238. for the user..n.n
  239. \li1050\ri1050 For instance, we just used the \\li and \\ri RTF 
  240. commands to squish this paragraph down.  This makes it stand out 
  241. from surrounding text..n
  242. \li180\ri180
  243. .box
  244. \brdrsh
  245. .b(NOTE:)  Another way to make text stand out is to place it in a 
  246. box (\'2ebox and \'2ebend macros).  This is the .i(most) common 
  247. method used in user manuals to highlight important information.  
  248. This particular box is a single line box with shading enabled.
  249. .bend
  250. .end
  251.  
  252. .com(=============================================================)
  253. .com( Creating the project file topic. )
  254. .com(=============================================================)
  255. .ent(createhpj,Creating the Project File, )
  256. When we are ready to compile our help file, we will need a project 
  257. file to tell the compiler how to compile it.  Follow these steps 
  258. when creating a project file:.n
  259. .in
  260. #n(1)Select the .b(Options | Project File) menu item.  Make sure 
  261. that all the listed options are set the way you want them.  Keep 
  262. in mind that in the shareware version of HelpGen, you can't change 
  263. the copyright notice..n
  264. #n(2)Select the .b(Build | Project File) menu item.  Answer 'Yes' 
  265. to the question and a project file will be built for you..n
  266. .un
  267. .end
  268.  
  269. .com(=============================================================)
  270. .com( Generating the RTF file topic. )
  271. .com(=============================================================)
  272. .ent(creatertf,Generating the RTF File, )
  273. When you have finished editing the macro file, you will want to 
  274. create an RTF file from the macro file.  Select the 
  275. .b(Build | RTF File) menu item to perform this step.
  276. .end
  277.  
  278. .com(=============================================================)
  279. .com( Generating the help file topic. )
  280. .com(=============================================================)
  281. .ent(createhlp,Generating the Help File, )
  282. When the RTF file has been built, HelpGen will enable the 
  283. generation of a help file.  Select the .b(Build | HLP File) menu 
  284. item and HelpGen will invoke the help compiler that you have 
  285. told it to use (see .b(Options | Directories)).
  286. .end
  287.  
  288. .com(=============================================================)
  289. .com( Testing the help file topic. )
  290. .com(=============================================================)
  291. .ent(testhlp,Testing the Help File, )
  292. After the help compiler generates a help file for you (assuming 
  293. that it did so with no errors), you can test the file.  To do this, 
  294. select the .b(Test) menu item.  HelpGen will invoke the WinHelp 
  295. help engine, using your help file.  You can then proceed with the 
  296. testing..n
  297. .end
  298.  
  299. .com(=============================================================)
  300. .com( Glossary topic. )
  301. .com(=============================================================)
  302. .ent(glossary,Glossary, )
  303. .in
  304. .bp(macro,newx.bmp) .b(Macro).n
  305. .bp(project,newx.bmp) .b(Project).n
  306. .bp(RTF,newx.bmp) .b(RTF).n
  307. .bp(rtfcmds,newx.bmp) .b(RTF Commands).n
  308. .un
  309. .end
  310.  
  311. .com(=============================================================)
  312. .com( Macro popup. )
  313. .com(=============================================================)
  314. .pent(macro,macro, )
  315. The replacement of a long series of .p1(RTF) commands with a single 
  316. command word and (optional) series of arguments.
  317. .end
  318.  
  319. .com(=============================================================)
  320. .com( Project popup. )
  321. .com(=============================================================)
  322. .pent(project,project, )
  323. A file with the extension .HPJ, that contains options that 
  324. specifies how a help file is to be built.  Required by the 
  325. help compiler.
  326. .end
  327.  
  328. .com(=============================================================)
  329. .com( RTF popup. )
  330. .com(=============================================================)
  331. .pent(RTF,RTF, )
  332. Rich Text Format, a standard text file formatting standard. An 
  333. RTF file consists of .p(rtfcmds,RTF commands) and normal text.
  334. .end
  335.  
  336. .com(=============================================================)
  337. .com( RTF commands popup. )
  338. .com(=============================================================)
  339. .pent(rtfcmds,RTF commands, )
  340. Special commands in an .p1(RTF) file that describe how text is to be 
  341. displayed.  These commands start with a backslash (\\) character.
  342. .end
  343.  
  344. .end_file
  345.